<html>
<head>
	<title>Marginalia Demo Installation</title>
	<style type="text/css">
		ol li {
			margin: 1em 0 ;
		}
	</style>
</head>
<body>
<h1>Marginalia Demo Installation</h1>

<p>The installation requires the following:</p>

<ul>
	<li>PHP 5 or later (PHP 4.3 or later probably still works)</li>
	<li>MySQL 4.1 or later (though a colleague has had success with MySQL 3; 
	I haven't tested with earlier versions or with Postgres)</li>
</ul>

<h2>Directory Structure</h2>

<p>If you're doing Marginalia development, you need to understand the directory
structure.  You may also wish to set up the demo with the most recent version of
the code from Subversion.  This demo is actually composed of three projects from
Subversion:  demo, marginalia-lib, and marginalia-php.</p>

<p>Your directory structure should look like this:</p>

<pre>
www/
  ...
  index.php
  ...
  marginalia/
    ...
    marginalia.js
    ...
  marginalia-php/
    ...
	AnnotationService.php
	...
</pre>

<p>The top level (<code>index.php</code>) is from the demo project.  The
<code>marginalia</code> subdirectory is from marginalia-lib and contains
the Javascript front-end user interface, while the <code>marginalia-php</code> 
subdirectory contains PHP back-end code shared with other Marginalia
integrations (e.g. Moodle and OJS).</p>

<h2>Option 1:  Use a Static XML Back-End</h2>

<p>Instead of setting up a database, you can simply run the demo off a static
XML file.  In this case, none of the changes you make will be saved, but you can
at least see how things work in principle.  Make sure the 
<code>RestAnnotationService</code> is commented-out
in <code>index.js</code>:</p>

<pre>
<code>
    // var annotationService = new RestAnnotationService( serviceRoot + '/annotate.php', { } );
    var annotationService = new StaticAnnotationService(serviceRoot, 'example-annotations.xml' );
</code>
</pre>

<p>Now the annotations will simply be taken from <code>example-annotations.xml</code>.
The database and most of the <code>.php</code> files will not be used.</p>


<h2>Option 2: Configure a Database Back-End</h2>

<p>If you want to be able to save annotations in the database, you must configure
the dynamic version of the annotation service.  Make sure <code>index.js</code> is
instantiating <code>RestAnnotationService</code>, not <code>StaticAnnotationService</code>,
which should look like this:</p>

<pre>
<code>
		var annotationService = new RestAnnotationService( serviceRoot + '/annotate.php', { } );
</code>
</pre>

<h3>Populate the Database</h3>

<p>Create a database and database user, then run <code>tables.sql</code>
scripts in the <code>util</code> directory.</p>

<h3>Update Configuration Files</h3>

<p>Rename <code>sample-config.php</code> to <code>config.php</code> and edit
it to include the correct database connection information.  You must
also update the <code>$CFG->host</code> and <code>$CFG->wwwapp</code> values.
For example, if the demo application is to be accessed at 
<code>http://localhost/annotation-demo</code>, then they should be set as
follows:</p>

<pre>
<code>
$CFG->host = 'localhost';
$CFG->wwwapp = 'annotation-demo';
</code>
</pre>

<p>Be certain the host name is exactly the same as what you will use from the
browser.  If your machine name is "george", you can't say "localhost" here
but use "http://george" in the browser.</p>

<p>If you want the Bungeni-style user interface features 
(including the "track changes" display of highlights), set <code>$CFG->bungeniStyle</code>
to <code>true</code>.</p>

<h2>Installation Problems</h2>

<p>If you have problems (e.g. you can create annotations but they disappear when you
reload the page), it is probably because of a misconfiguration.  First, make sure
that the URL through which you are accessing the application matches the one in
<kbd>config.php</kbd>.  If you are using a different url (e.g. <kbd>localhost</kbd>
instead of a numerical IP address), annotation will not work.</p>

<p>If your URL matches your configuration, I recommend installing and running the Firebug
extension for Firefox.  Among other things, it tracks AJAX requests from a web page to
the server.  The first thing to look for (other than any explicit errors reported by
Firebug) is the URL of the GET request sent to annotation/annotate.php with the parameter
"format=atom" when a page with annotations is first loaded.  Trying loading this URL
on its own in a browser window:  it should return an Atom feed containing the annotations
for that page.</p>

<h2>Known Issues</h2>

<ul>
<li>This is a demo, not a full web application.  As such, it may not be secure enough 
to run as a web application on the Internet.</li>
<li>Marginalia includes a feature to protect against cross-site request forgery when
creating and updating annotations (though not, as yet, for preferences and keywords).
However, this feature is not properly implemented in the demo (again because this is
not a proper web application).</li>
</ul>


</body>
</html>

